.Dd Jul 5, 2018
.Dt AUPLAYER 1
.Os
.Sh NAME
.Nm auplayer
.Nd a CLI for playing audio files
.Sh SYNOPSIS
.Nm
.Op Fl lprsv
.Op Fl F Ar file-descriptor
.Op Fl I Ar file-descriptor
.Op Fl b Ar buffer-size
.Op Fl c Ar command
.Op Fl d Ar device
.Op Fl f Ar file-list
.Op Fl g Ar file-list
.Op Fl h Ar history-size
.Op Fl i Ar input-file
.Ar arg ...
.Sh DESCRIPTION
.Nm
provides a simple command-line interface for playing audio files.
.Pp
The arguments are as follows:
.Bl -tag -width Ds
.It Fl F Ar file-descriptor
Add lines read from
.Ar file-descriptor
to the playlist as below, removing leading & trailing white-space.
.It Fl I Ar file-descriptor
Read commands from
.Ar file-descriptor
instead of the standard input.
.It Fl b Ar buffer-size
Specify the buffer size for
.Xr auopen 1 .
.br
Additionally, append
.Qq Fl b Ar buffer-size
to the end of the shell command string.
.It Fl c Ar command
Specify the shell command to execute when playing audio.
.sp
If
.Ar command
is empty then
.Nm
does not try to play files, does not look-up files when using the
.Sy a
command, and does not exit if there are no more entries available.
.br
This is to aid in testing.
.It Fl d Ar device
Append
.Qq Fl d Ar device
to the end of the shell command string.
.It Fl f Ar file-list
Add each line of
.Ar file-list
to the playlist as below, removing leading & trailing white-space.  If
.Ar file-list
is
.Qq -
then the standard input is read instead.
.It Fl g Ar file-list
.Xr glob 3
each line of
.Ar file-list ,
after removing the leading & trailing white-space, adding the results to
the playlist as below.  If
.Ar file-list
is
.Qq -
then the standard input is read instead.
.It Fl h Ar history-size
Specify the number of elements to keep in history.
.It Fl l
After playing the last file loop back to the beginning instead of
exiting, reshuffling if
.Fl s
is specified.  This option has no effect if
.Fl r
is specified.
.It Fl i Ar input
Read commands from
.Ar input
instead of the standard input.
.It Fl p
Have
.Nm
behave in a manner suitable for being controlled by another program.
.Pp
.Nm
will print information in a parse friendly format:
.Bl -tag -width Ds
.It Sy : Ar time Sy / Op Ar total
The current position and total length of the current file.  For example:
.Qq : 0:12:34.56/1:23:45.67 .
.It Sy ! Ar string
Information about the internal state.  For example
.Qq !pause
and
.Qq !unpause .
.It Sy @ Ar path
The path of the currently playing entry.
.It Sy + Ar path
The specified path was appended to the playlist.
.It Sy - Ar path
The specified path was removed from the playlist.
.El
.Pp
This option supersedes
.Fl v .
.It Fl r
Play the audio files in a random order.
.It Fl s
Shuffle the list of audio files.
.It Fl v
Enable verbose output.
.It Ar \&(
Begin an ordered sub-group.
.It Ar (r
Begin a random sub-group.
Random sub-groups play one random entry each time it is selected.
Trailing characters are ignored.
.It Ar (s
Begin a shuffled sub-group.
Trailing characters are ignored.
.It Ar \&)
End a sub-group list.
.It Ar file
Append
.Ar file
to the list of files.  If it is a directory, non-recursively append its,
sorted, entries to the list of files.
.El
.Pp
If no input is selected, and the standard input was specified by
.Fl f ,
then the input will be read from
.Qq /dev/tty .
However, the
.Fl p
option will cause an error to be produced instead.
.Sh COMMANDS
Commands have the following global syntax:
.Pp
.Op count
.Li c
.Op argument
.Pp
Where
.Sy c
is the command character.
.Pp
The available commands are as follows:
.Bl -tag -width Ds
.It Sy \&(
Begins a sub-group as above.
.Ar count
is ignored.
.It Sy \&)
Ends a sub-group as above.  Both
.Ar count
and
.Ar argument
are ignored.
.It Sy +
Seek forwards by
.Ar argument .
.Ar count
is ignored.
.It Sy -
Seek backwards by
.Ar argument .
.Ar count
is ignored.
.It Sy =
Seek to the time specified by
.Ar argument .
If
.Ar argument
is negative the seek is relative to the end of the file.
.Ar count
is ignored.
.It Sy ?
Print the current file, the position in it, and its length.  Both
.Ar count
and
.Ar argument
are ignored.
.It Sy /
Search forward for
.Ar argument
and move to the matching entry, if any.
.Ar count
is ignored.
.It Sy L
Toggle looping.  Both
.Ar count
and
.Ar argument
are ignored.
.It Sy V
Toggle verbosity.  Both
.Ar count
and
.Ar argument
are ignored.
.It Sy a
Append files matched by
.Ar argument
to the file list.
.Ar count
is ignored.
.It Sy d
If an argument is given, remove any entries that match
.Ar argument ,
otherwise remove the current entry.
.Ar count
is ignored.
.It Sy h
Go back
.Ar count
entries.
.Ar argument
is ignored.
.It Sy i
A synonym for
.Sy ? .
.It Sy j
A synonym for
.Sy h .
.It Sy k
Go forward
.Ar count
entries.
.Ar argument
is ignored.
.It Sy l
A synonym for
.Sy k .
.It Sy p
Toggle the pause state.  Both
.Ar count
and
.Ar argument
are ignored.
.It Sy q
Exit
.Nm .
Both
.Ar count
and
.Ar argument
are ignored.
.It Sy r
Replay the current entry.  Both
.Ar count
and
.Ar argument
are ignored.
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr auopen 1
.Xr au2dev 1
.Xr glob 3
